home *** CD-ROM | disk | FTP | other *** search
/ Aminet 32 / Aminet 32 (1999)(Schatztruhe)[!][Aug 1999].iso / Aminet / dev / lang / Python151_Src.lha / Python1.5_Source / Amiga_Misc / Docs / general < prev    next >
Text File  |  1998-12-05  |  11KB  |  250 lines
  1.  
  2.              GENERAL NOTES ON THE AMIGA VERSION OF PYTHON 1.5
  3.  
  4.                      Irmen de Jong - irmen@bigfoot.com
  5.                                 9 dec. 1998
  6.  
  7.  
  8. REGULAR PYTHON DOCUMENTATION AND RESOURCES
  9. ------------------------------------------
  10.  
  11. This  Amiga  documentation assumes you are familiar with Python in general.
  12. If  not,  the  base  documentation  (tutorial, language reference guide and
  13. library reference manual) can be obtained from http://www.python.org.  This
  14. is  the main Python site.  This documentation is also available from Aminet
  15. (www.aminet.org)   as   dev/lang/Python_Doc.lha,   and  this  may  be  more
  16. convenient  because  this  is compressed with our well-known LhA instead of
  17. Unix tar and gzip.
  18.  
  19.  
  20. MODULE SEARCH PATH (changed again in 1.5)
  21. -----------------------------------------
  22.  
  23. Version  1.4  introduced  a  different treatment of the module search path.
  24. The  current  directory  is  no longer by default part of the module search
  25. path.   Instead,  the  following  procedure  gives  the  module search path
  26. (sys.path):
  27.  
  28. - sys.path is set to the default PYTHONPATH, which is "Python:lib"
  29. - if  the  global  environment  variable  PYTHONPATH is set, the paths listed
  30.   there  will be inserted before the default path.  PYTHONPATH is a semicolon
  31.   (;) separated list of directories, like "WORK:pylib;Python:lib/mymods".
  32. - the  path of the script which was given as an argument is inserted in front
  33.   of the search path. If no script was given as argument, '' will be inserted
  34.   (which is the current directory).
  35.  
  36. Version 1.5 introduced yet more changes to this behavior.  From Misc/NEWS:
  37.  
  38. "The  default  module  search  path  is  now  much saner.  Both on Unix and
  39. Windows  [and  Amiga],  it  is  essentially  derived  from  the path to the
  40. executable  (which  can  be  overridden by setting the environment variable
  41. $PYTHONHOME)."
  42.  
  43. "On Unix, when using sys.argv[0] to insert the script directory in front of
  44. sys.path,  expand  a  symbolic  link.   You  can now install a program in a
  45. private directory and have a symbolic link to it in a public bin directory,
  46. and it will put the private directory in the module search path.  Note that
  47. the  symlink  is expanded in sys.path[0] but not in sys.argv[0], so you can
  48. still tell the name by which you were invoked."
  49.  
  50. "More  changes  to  import:   the site.py module is now imported by default
  51. when  Python  is  initialized;  use  -S  to disable it.  The site.py module
  52. extends  the  path with several more directories:  site-packages inside the
  53. lib/python1.5/  directory, site-python in the lib/ directory, and pathnames
  54. mentioned  in  *.pth  files  found  in  either  of  those directories.  See
  55. http://grail.cnri.reston.va.us/python/essays/packages.html for more info."
  56.  
  57. For  those  who  want  to  know  everything,  see the source of the GetPath
  58. function (Modules/getpath.c). Ofcourse you should also read the manual.
  59.  
  60.  
  61. MODULE FILENAMES AND CASE SENSITIVITY
  62. -------------------------------------
  63.  
  64. AmigaPython  now checks the case of the imported module against the case of
  65. the module's filename.  Say you try to "import stringio", this used to work
  66. in  the old versions of AmigaPython but now you will get an error.  This is
  67. because  the  module's  file  is named "StringIO.py" and not "stringio.py":
  68. the  case is different.  If you don't like this behavior (because it breaks
  69. too  much  existing  code,  for instance) you can disable it by setting the
  70. local or global environment variable PYTHONCASEOK to some value.
  71.  
  72.  
  73. AMIGA SPECIFIC MODULES
  74. ----------------------
  75.  
  76. Version  1.4 introduced a clean way of installing platform specific library
  77. files.   In  the Lib drawer there is anoter drawer called site-python.  All
  78. Amiga  specific modules are put here.  There is a simple way of using them:
  79. place the
  80.  
  81.     import site
  82.  
  83. statement  somewhere  at  the  top  of all code that must use site-specific
  84. modules.   This  will  modify  the module search path and also run any site
  85. specific  initialization code (by importing the sitecustomize module, which
  86. should  also  be  placed in the site-python drawer).  Currently there is no
  87. sitecustomize  module  on  the Amiga.  If you don't like to import the site
  88. module (why?) just use sys.path.append('Python:Lib/site-python').
  89.  
  90. You  can  now  simply import any Amiga specific modules, regardless of them
  91. being built-in (like ARexxll) or in a .py source file:
  92.  
  93.     import ARexx
  94.  
  95. NOTE!  For version 1.5, site.py is imported by default.  (see above) Unless
  96. you use the -S command line argument.
  97.  
  98.  
  99.  
  100. POSIX REPLACEMENTS
  101. ------------------
  102.  
  103. In  lib/ there is a dummy module `posixpath'.  It just imports `amigapath',
  104. thereby  making  some  other  modules and files work because they don't use
  105. os.path but posixpath.
  106.  
  107.  
  108. About the networking support (AmiTCP)
  109. -------------------------------------
  110.  
  111. The  python  binary is compiled with AmiTCP support.  The interpreter still
  112. works  even  if  you don't have AmiTCP, but the extra functionality (mainly
  113. the  socket  module)  can't be used without AmiTCP (obviously).  Some extra
  114. functions  already work if you only have the usergroup.library, and not the
  115. full  AmiTCP  package:   the  crypt,  pwd  and grp modules for instance.  A
  116. MultiuserFileSystem-compatible  usergroup.library can be found on Aminet (I
  117. didn't  try it -- beware).  Usergroup.library can also be found in the demo
  118. version of AmiTCP, which is also on Aminet.
  119.  
  120. Python is compiled for version 4 of AmiTCP.  Maybe it works with version 3
  121. too, but I haven't tried it.
  122.  
  123.  
  124. About Timezones
  125. ---------------
  126.  
  127. As  another  side-effect  of  linking  in AmiTCP stuff, Python extracts the
  128. timezone information from your current locale preferences.  No need anymore
  129. for a TZ environment var.  (One small problem:  the name of the timezone is
  130. no longer known, and is replaced by '???'.) If the locale prefs couldn't be
  131. read, the timezone information is taken from ENV:TZ, which must be a string
  132. like 'MET-1' (MET, -1 hour from GMT).
  133.  
  134.  
  135. sys.platform
  136. ------------
  137.  
  138. This is defined as 'amiga'. No upper case A.
  139.  
  140. os.uname
  141. --------
  142.  
  143. The machine information correctly identifies the Kickstart release version
  144. and determines if you have a 1.x, 2.x or 3.x machine.
  145.  
  146. os.popen
  147. --------
  148.  
  149. When opening a pipe for writing (like f=os.popen('command','w')), using the
  150. standard  'More'  command  doesn't  work.   This is a fault of More.  Use a
  151. better pager like Most (available on Aminet).
  152.  
  153. About modifying library files
  154. -----------------------------
  155.  
  156. You  should  not  change anything in one of the library files.  The library
  157. files  should  always  behave the same on all platforms that supports them.
  158. (Note:   I  said BEHAVE.  You are free to modify the implementation but the
  159. BEHAVIOR should remain the same.)
  160. Put Amiga specific library files in the right place: lib/site-python.
  161.  
  162.  
  163. Workbench startup
  164. -----------------
  165.  
  166. [NOTE:   This  paragraph has been rewritten and also describes new features
  167. in Python 1.5.1 buildnumber 13 and higher!  (marked 'NEW in #13')]
  168.  
  169. Since  1.4,  Amiga Python contains some code to make it possible to use the
  170. Workbench  to start python or python programs.  The interpreter already has
  171. an  icon.   Doubleclick  it  to  start python in interactive mode.  Use the
  172. well-known multiselect (shift-click) to select any scripts to execute.  Any
  173. additional  files  which  are multi-selected will be passed as command line
  174. arguments.
  175.  
  176. PRECISE DESCRIPTION OF HOW THE WORKBENCH STARTUP CODE WORKS:
  177.  
  178. 1. Just starting Python from the Workbench.
  179.    Tooltypes are converted to command-line arguments.
  180.    One tooltype is one argument. So to specify '-v -t -i' as command line
  181.    arguments, you must have three tooltypes. One -v, one -t and one -i.
  182.  
  183. 2. Multiselecting Python with a Python script.
  184.    The script is executed. Tooltypes from the script's icon are appended to
  185.    the arguments from the tooltypes from Python's icon.
  186.  
  187. 3. Datafile with project icon normally used for Python scripts.
  188.    Python tries to start the datafile as a Python script, which is not what
  189.    you want. But see below under: DATA FILES.
  190.  
  191. SCRIPT  ICONS.
  192. Look  in  the  `Icons'  directory  for icon templates:  use def_py.info and
  193. def_pyc.info  as icon templates for .py and .pyc files.  Just make sure the
  194. default  tool  is  set  to  `Python:Python'.  Any tooltypes in the icon are
  195. converted  to  command  line  arguments  for  the  Python  interpreter (one
  196. tooltype is exactly one command line argument).
  197.  
  198. MAGIC TOOLTYPES.    [NEW in #13]
  199. Two  'magic  tooltypes'  have been defined to make it easier to control the
  200. way Python parses the icons and tooltypes.  They are 'PYTHONSCRIPT=...' and
  201. 'PYSCRIPTARG=...'.  See below for a description.
  202.  
  203. DATA FILES.    [NEW in #13]
  204. It  is  possible to start Python with a given script by doubleclicking on a
  205. DATA  FILE'S ICON!  You can associate a Python script as a default tool for
  206. project  (data)  files!   To  do  this, give the data file the usual Python
  207. script   icon.    The   icon's  default  tool  should  already  be  set  to
  208. Python:Python.   Add  ONE  tooltype  at  the top containing the name of the
  209. script you want to run.  Doubleclick the datafile's icon and voila:  Python
  210. starts  running the specified script which gets the datafile as an argument
  211. in  sys.argv  (and possibly other specified tooltypes too)!  NOTE:  to make
  212. things  clearer  and  easier,  a  special  magic tooltype has been defined:
  213. PYTHONSCRIPT=..., where ...  must be your script.  Using this tooltype will
  214. just  put  your  script  in  front of all other tooltypes so it will be the
  215. first command line argument, and thus be executed as script.
  216.  
  217. SCRIPT ARGUMENTS TOOLTYPES.    [NEW in #13]
  218. Before  1.5.1  #13  it  was not possible to pass any parameters to a Python
  219. script  started  from  Workbench.   But  since  the  addition  of the magic
  220. tooltype  'PYSCRIPTARG=...'  this  is  no  longer a problem.  This tooltype
  221. causes  the  '...'  part to be moved to the end of the argument list, after
  222. the  script  name.   So  it will become a parameter string for your script,
  223. instead  of  a  Python interpreter option.  Note that in the case of a data
  224. file  (as described above) the data file's filename will be placed *before*
  225. the script arguments.
  226.  
  227. NO-SCRIPT PYTHON SCRIPTS?!
  228. Another  nice  tricks  is this:  it is possible to embed a Python script in
  229. the  icon alone, no scriptfile on disk needed.  Remember that all tooltypes
  230. are  converted  to  command line parameters.  So make a tooltype '-c' and a
  231. NEW TOOLTYPE directly below it, containing the script code, without quotes.
  232. Example:
  233.  
  234. -c
  235. import os,sys; print sys.argv; print os.uname()
  236.  
  237.  
  238. SOURCE CODE and other files
  239. ---------------------------
  240.  
  241. For  the original source code distribution, which also includes all library
  242. files,    a    bunch   of   docs   and   many   example   programs,   check
  243. http://www.python.org.    BTW,   this  site  contains  a  lot  more  stuff:
  244. reference  manuals,  contributed  files, online documentation, FAQ's, news,
  245. etc.  etc.
  246.  
  247. For the Amiga source code, see Aminet in the same location as you found
  248. this.  It should be named `Python_Src.lha'.
  249.  
  250.